Add runtime feature flag support by stanleyphu · Pull Request #72 · workos/authkit-react-router

stanleyphu · 2026-06-22T22:10:33Z

Summary

add a shared getFeatureFlagsRuntimeClient helper for the WorkOS Feature Flags runtime client
allow authkitLoader to populate auth.featureFlags from a configured runtime client
add onFeatureFlagsError so applications can report runtime evaluation failures before falling back to JWT feature_flags
document token vs runtime-client feature flag source behavior
bump @workos-inc/node minimum to ^8.13.0 for runtime-client APIs

Test plan

greptile-apps · 2026-06-22T22:22:24Z

Greptile Summary

This PR adds runtime feature flag support to authkitLoader so applications can evaluate flags server-side using the WorkOS Feature Flags runtime client instead of relying solely on the feature_flags JWT claim. It also introduces onFeatureFlagsError for production-safe error reporting when the runtime client fails, with automatic fallback to the JWT claim.

getFeatureFlagsRuntimeClient — new module-level singleton (via the generalized lazy helper) that creates one FeatureFlagsRuntimeClient per server process; the @workos-inc/node minimum is bumped to ^8.13.0 for the required APIs.
getFeatureFlags in session.ts — new async helper called unconditionally after claims extraction; when a runtime client is configured it calls waitUntilReady (optional) then getAllFlags, filters to enabled flags, and falls back to JWT flags on any error while invoking onFeatureFlagsError and/or a debug warn.
Tests — four new scenarios cover the happy path, waitUntilReady failure, getAllFlags failure, and debug-mode logging, with proper module isolation in feature-flags.spec.ts.

Confidence Score: 5/5

Safe to merge — the new runtime flag evaluation path has clean fallback semantics and is well-tested, with no changes to the existing auth or session refresh flows.

The feature flag evaluation is fully opt-in, isolated to a new getFeatureFlags helper, and always falls back to the JWT claim on error. Existing session handling is untouched. The test suite covers the happy path, both error modes (waitUntilReady and getAllFlags failures), and debug-mode logging.

No files require special attention.

Important Files Changed

Filename	Overview
src/feature-flags.ts	New file: exports a module-level singleton `getFeatureFlagsRuntimeClient` using the existing `lazy` helper; straightforward and correct.
src/session.ts	Adds `getFeatureFlags` helper with `onFeatureFlagsError` callback and `debug` warn; error handling, fallback, and ordering are correct. One `// istanbul ignore next` comment is now redundant since a test directly covers that branch.
src/utils.ts	Generalizes `lazy` to accept and forward arguments on the first call; subsequent calls return the cached result regardless of arguments. Correct and well-tested.
src/interfaces.ts	Adds `FeatureFlagsErrorOptions` and `AuthKitFeatureFlagsOptions` interfaces, and extends `AuthKitLoaderOptions` with `featureFlags` and `onFeatureFlagsError`; types are sound.
src/feature-flags.spec.ts	Tests singleton memoization for `getFeatureFlagsRuntimeClient`; uses `jest.resetModules` and dynamic import to avoid cross-test pollution, which is the right approach.
src/session.spec.ts	Adds four new scenarios: runtime-client happy path, `waitUntilReady` failure fallback, `getAllFlags` failure fallback, and debug-mode warn. Coverage is thorough for the new code paths.
src/utils.spec.ts	New test verifies that arguments are forwarded only on the first call and the cached result is returned on subsequent calls; correctly documents `lazy` semantics.
src/index.ts	Re-exports `getFeatureFlagsRuntimeClient` from the new module; no issues.

Sequence Diagram

%%{init: {'theme': 'neutral'}}%%
sequenceDiagram
    participant Route as Route Loader
    participant AL as authkitLoader
    participant GFF as getFeatureFlags
    participant RC as FeatureFlagsRuntimeClient
    participant CB as onFeatureFlagsError

    Route->>AL: "authkitLoader(args, { featureFlags, onFeatureFlagsError })"
    AL->>AL: getClaimsFromAccessToken to tokenFeatureFlags
    AL->>GFF: "getFeatureFlags({ options, tokenFeatureFlags, user, ... })"

    alt featureFlags option not set
        GFF-->>AL: return tokenFeatureFlags (JWT claims)
    else featureFlags.runtimeClient configured
        alt waitUntilReady enabled
            GFF->>RC: waitUntilReady(timeoutMs?)
        end
        GFF->>RC: "getAllFlags({ userId, organizationId })"
        RC-->>GFF: Record of string to boolean
        GFF->>GFF: "filter enabled=true to string[]"
        GFF-->>AL: return runtimeFeatureFlags

        note over GFF,RC: On any error in try block
        GFF->>CB: "onFeatureFlagsError({ error, request, user, ... })"
        opt debug: true
            GFF->>GFF: console.warn(fallback message)
        end
        GFF-->>AL: return tokenFeatureFlags (fallback)
    end

    AL-->>Route: auth.featureFlags populated

%%{init: {'theme': 'base', 'themeVariables': {"darkMode": true, "background": "#0d1117", "primaryColor": "#21262d", "primaryTextColor": "#e6edf3", "primaryBorderColor": "#8b949e", "lineColor": "#8b949e", "textColor": "#e6edf3", "edgeLabelBackground": "#161b22", "actorBkg": "#21262d", "actorBorder": "#8b949e", "actorTextColor": "#e6edf3", "actorLineColor": "#8b949e", "signalColor": "#8b949e", "signalTextColor": "#e6edf3", "noteBkgColor": "#373320", "noteBorderColor": "#d4a72c", "noteTextColor": "#f0e6c0", "labelBoxBkgColor": "#21262d", "labelBoxBorderColor": "#8b949e", "labelTextColor": "#e6edf3", "loopTextColor": "#e6edf3", "activationBkgColor": "#30363d", "activationBorderColor": "#8b949e"}}}%%
sequenceDiagram
    participant Route as Route Loader
    participant AL as authkitLoader
    participant GFF as getFeatureFlags
    participant RC as FeatureFlagsRuntimeClient
    participant CB as onFeatureFlagsError

    Route->>AL: "authkitLoader(args, { featureFlags, onFeatureFlagsError })"
    AL->>AL: getClaimsFromAccessToken to tokenFeatureFlags
    AL->>GFF: "getFeatureFlags({ options, tokenFeatureFlags, user, ... })"

    alt featureFlags option not set
        GFF-->>AL: return tokenFeatureFlags (JWT claims)
    else featureFlags.runtimeClient configured
        alt waitUntilReady enabled
            GFF->>RC: waitUntilReady(timeoutMs?)
        end
        GFF->>RC: "getAllFlags({ userId, organizationId })"
        RC-->>GFF: Record of string to boolean
        GFF->>GFF: "filter enabled=true to string[]"
        GFF-->>AL: return runtimeFeatureFlags

        note over GFF,RC: On any error in try block
        GFF->>CB: "onFeatureFlagsError({ error, request, user, ... })"
        opt debug: true
            GFF->>GFF: console.warn(fallback message)
        end
        GFF-->>AL: return tokenFeatureFlags (fallback)
    end

    AL-->>Route: auth.featureFlags populated

_{Reviews (2): Last reviewed commit: "Add feature flag error hook" | Re-trigger Greptile}

stanleyphu added 2 commits June 22, 2026 12:31

Add runtime feature flag support

4264b00

Clarify feature flag source behavior

7eec032

greptile-apps Bot reviewed Jun 22, 2026

View reviewed changes

Comment thread src/session.ts

Comment thread src/session.spec.ts Outdated

Add feature flag error hook

28e1ecb

gjtorikian approved these changes Jun 23, 2026

View reviewed changes

stanleyphu merged commit 60d3197 into main Jun 23, 2026
8 checks passed

stanleyphu deleted the feat/ff-runtime-client-helper branch June 23, 2026 16:38

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add runtime feature flag support#72

Add runtime feature flag support#72
stanleyphu merged 3 commits into
mainfrom
feat/ff-runtime-client-helper

stanleyphu commented Jun 22, 2026 •

edited

Loading

Uh oh!

greptile-apps Bot commented Jun 22, 2026 •

edited

Loading

Sequence Diagram

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

stanleyphu commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Test plan

Uh oh!

greptile-apps Bot commented Jun 22, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Greptile Summary

Confidence Score: 5/5

Important Files Changed

Sequence Diagram

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

2 participants

stanleyphu commented Jun 22, 2026 •

edited

Loading

greptile-apps Bot commented Jun 22, 2026 •

edited

Loading